<HTML>
<TITLE>module cloud_obs</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>module cloud_obs</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Bruce Wyman
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#cloud_obs.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     Provides a spatial observed cloud fraction derived from
     monthly mean ISCCP cloud data.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

     This module uses monthly mean climatological ISCCP cloud amount
     for the period (1984-1989 ?).

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

      horiz_interp_mod
         utilities_mod
      time_manager_mod
       time_interp_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

  use cloud_obs_mod [, only:  cloud_obs_init, cloud_obs ]

    cloud_obs_init - Must be called once before cloud_obs is called.
                     Reads the namelist and sets up constants needed
                     for interpolation onto the model grid.

    cloud_obs      - Returns observed cloud amounts for high, middle,
                     and low clouds at the requested time of year.

  Notes:

    1) The optional namelist interface called &cloud_obs_nml
       is read from file <b>input.nml</b>.

    2) The observed cloud amount data set is read from file
       <b>INPUT/cloud_obs.data</b>.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

   call cloud_obs_init (lonb,latb)

    lonb  =   longitude in radians of the grid box edges
                [real, dimension(nlon+1)]
    latb  =   latitude in radians of the grid box edges
                [real, dimension(nlat+1)]

    nlon and nlat are the number of x and y grid points in the
    entire grid

-----------------------------------------------------------------------

    call cloud_obs (is, js, time, cldamt)

    routine that reads monthly records of climatological
    isccp cloud amount and then linearly interpolates between them

     input
     -----
     is,js    starting i,j global indices (integer)
     time     current time (time_type)

     output
     ------
     cldamt    cloud amount data (for high,middle,low clouds),
               a sub-window starting at i,j given by istart
                [real, dimension(nlon,nlat,3)]

     In call cloud_obs, nlon and nlat are the number of x and y
     grid points in a sub-window.


</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&cloud_obs_nml</b>

   use_climo   Flag that determines whether monthly mean data or
               monthly mean climatological data should be used.
               <b>Currently this option does nothing, only climatological
               data can be used.</b>
                  [logical, default: use_climo = .true.]

   verbose     Flag that controls the amount of printed output
               (verbose = 0 will print nothing).
                  [integer, default: verbose = 0]

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DATA_SETS">
<HR>
<H4>DATA SETS</H4>
<!-- BEGIN DATA_SETS -->
<PRE>

     The observed monthly mean climatological data is read from file
     INPUT/cloud_obs.data. The file format is 32-bit IEEE.

     The data has a resolution of 2.5 x 2.5 deg (144 x 72).
     The first grid point is at (-88.75, 1.25).

     The original ISCCP low cloud amounts were modified using the
     total cloud amount.

</PRE>
</A><!-- END DATA_SETS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#cloud_obs.f90">CVS Revision history</A></B>


<B>Changes prior to CVS version control</B>

   Removed duplicate is,js declaration.
   Changed close statement to call close_file (for ieee data).


   MPP version created.
   Input argument istart changed to is, js.


  * time interpolation done by time_interp_mod
  * namelist added

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Fatal Error in cloud_obs (or observed_cloud):</b>

    <b>cloud_obs_init has not been called</b>
          The modules has not been initialized. 
          You must call cloud_obs_init before calling cloud_obs.

    <b>dimension 3 of cldamt is < 3</b>
          Routine cloud_obs returns high, middle, and low cloud amounts,
          therefore for output argument cldamt the third dimension must
          be at least 3.

    <b>file INPUT/cloud_obs.data does not exist</b>
          The observed data set is not where the module will try
          to read it. Check the <A HREF="#DATA_SETS">data set section</A> on how to set up
          the observed data set.

    <b>eof reading file=INPUT/cloud_obs.data</b>
          The data was read and no match was found for the date
          you requested. This error should not occur. It it does
          contact the developer.

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     None.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     None.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

     None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     Return ISCCP radiative cloud propertities.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
